/**
 * Copyright (c) 2006-2012 Las Venturas Playground, LVP Mineground
 *
 * This program is free software: you can redistribute it and/or modify it under the terms of the
 * GNU General Public License as published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
 * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with this program.
 * If not, see <http://www.gnu.org/licenses/>.
 */

package mineground.core;

import java.util.concurrent.Callable;

/**
 * The Message Loop forms the core of the Las Venturas Mineground mode, managing the communication
 * between several threads allowing an event-based multi-threaded architecture.
 * 
 * There are two concepts available for communicating to other threads. There are tasks, allowing
 * certain pieces of code to be executed on a predefined thread, and Messages which will broadcast
 * events to all listeners on a certain thread.
 * 
 * ** Posting a task to a certain thread may be done through the following methods. All these
 *    methods are completely thread-safe and my be used at any time. Since these are asynchronous,
 *    no feedback will be given as to whether they were successful.
 * 
 *    ** void postTask(MessageLoopThread target, Runnable task)
 *
 *       Post a one-shot task to the target thread of your choice. The runnable will be executed
 *       as soon as capacity is available.
 *
 *    ** void postDelayedTask(MessageLoopThread target, Runnable task, long delayInMilliseconds)
 * 
 *       Post a one-shot task to the target thread of your choice. The runnable will be executed
 *       after a certain delay, to be indicated with the delayInMilliseconds parameter.
 * 
 *    ** int postRepeatingTask(MessageLoopThread target, Runnable task, long intervalInMilliseconds)
 * 
 *       Post a task to the thread of your choice which is to be repeated every few milliseconds, as
 *       will be indicated through the intervalInMilliseconds parameter. The first invocation will
 *       take place after this interval has passed.
 *       
 *    ** void cancelRepeatingTask(int repeatingTaskId)
 *   
 *       Cancel a previously instated repeating task indicated by its Id. The task cannot be
 *       guaranteed to not execute after invoking this method, but generally shouldn't.
 * 
 * ** In case it's necessary to know the return value of the code executed on a certain thread, as
 *    could be the case for very important calls to the native API, the following synchronous method
 *    may be used. Usage of this method is VERY STRONGLY DISCOURAGED, as it could block the current
 *    thread for tens of milliseconds.
 *    
 *    ** <Type> postSynchronousTask<Type>(MessageLoopThread target, Callable<Type> task)
 *    
 *       Queue the given task on the chosen thread and wait until it has been executed, after which
 *       the return value will be returned. This will block execution on the current thread.
 *
 * @TODO Implement Messages.
 */
public interface MessageLoop {
    
    /** Methods related to posting tasks to other threads. **/
    
    public void postTask(MessageLoopThread targetThread, Runnable runnable);

    public void postDelayedTask(MessageLoopThread targetThread, Runnable runnable,
                                int delayInMilliseconds);

    public int postRepeatingTask(MessageLoopThread targetThread, Runnable runnable,
                                 int intervalInMilliseconds);

    public void cancelRepeatingTask(int repeatingTaskId);

    public <Type> Type postSynchronousTask(MessageLoopThread targetThread, Callable<Type> task);

    /** Methods related to posting messages to other threads. **/
    
    // @TODO
    public void postMessage(MessageLoopThread targetThread, Message message, Object... params);
    
    /** Methods which control functionality of the message loop. **/
    
    public void run(MessageLoopThread thread);
}
